useGetTokenBalancesSummary

Hook for fetching summarized token balances across multiple chains

Import

import { useGetTokenBalancesSummary } from '@0xsequence/hooks'

Usage

import React from 'react'
import { useGetTokenBalancesSummary } from '@0xsequence/hooks'
import { ContractVerificationStatus } from '@0xsequence/connect'
import { useAccount } from 'wagmi'
import { formatUnits } from 'viem'

function TokenBalancesList() {
  const { address } = useAccount()
  
  const {
    data: tokens,
    isLoading,
    isError
  } = useGetTokenBalancesSummary({
    chainIds: [1, 137], // Ethereum and Polygon
    filter: {
      accountAddresses: [address || ''],
      omitNativeBalances: false,
      contractStatus: ContractVerificationStatus.VERIFIED,
      // Optional: filter specific tokens
      contractWhitelist: [
        '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
        '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'  // WETH
      ]
    }
  })

  if (isLoading) return <div>Loading balances...</div>
  if (isError) return <div>Error loading balances</div>

  return (
    <div className="token-list">
      {tokens?.map(token => (
        <div 
          key={`${token.chainId}-${token.contractAddress}`}
          className="token-item"
        >
          <div className="token-info">
            {token.contractInfo?.logoURI && (
              <img 
                src={token.contractInfo.logoURI}
                alt={token.contractInfo.symbol}
                width={32}
                height={32}
              />
            )}
            <div>
              <h4>{token.contractInfo?.symbol || 'Unknown'}</h4>
              <p>{token.contractInfo?.name}</p>
            </div>
          </div>
          
          <div className="token-balance">
            <span>
              {token.contractInfo?.decimals
                ? formatUnits(token.balance, token.contractInfo.decimals)
                : token.balance}
            </span>
            <span className="chain-badge">
              Chain: {token.chainId}
            </span>
          </div>
        </div>
      ))}
    </div>
  )
}

Return Type: UseQueryResult<TokenBalance[]>

The hook returns all properties from React Query’s UseQueryResult with token balance data. Here’s the detailed structure:

interface TokenBalance {
  contractType: ContractType
  contractAddress: string
  accountAddress: string
  balance: string
  blockHash: string
  blockNumber: number
  chainId: number
  uniqueCollectibles: string
  isSummary: boolean
  contractInfo?: {
    name: string
    symbol: string
    decimals: number
    logoURI: string
  }
}

Properties

data

TokenBalance[] | undefined

Array of token balance objects containing:

• contractType: Type of the token contract (NATIVE, ERC20, ERC721, ERC1155)
• contractAddress: Address of the token contract
• accountAddress: Address of the account holding the tokens
• balance: Token balance as a string (in base units)
• chainId: Chain ID where the token exists
• blockHash: Hash of the block where balance was last updated
• blockNumber: Block number where balance was last updated
• uniqueCollectibles: Number of unique collectibles
• isSummary: Whether the balance is a summary
• contractInfo: Basic token contract information including name, symbol, decimals, and logo URL

isLoading

boolean

Loading state for the data fetch.

isError

boolean

Error state indicating if the query failed.

error

Error | null

Any error that occurred during data fetching.

Parameters

The hook accepts two parameters:

args: GetTokenBalancesSummaryArgs

interface GetTokenBalancesSummaryArgs {
  chainIds: number[]
  filter: {
    accountAddresses: string[]
    contractWhitelist?: string[]
    contractBlacklist?: string[]
    omitNativeBalances?: boolean
    contractStatus?: ContractVerificationStatus
  }
}

Parameter	Type	Description
chainIds	number[]	Array of chain IDs to fetch balances from
filter.accountAddresses	string[]	Array of account addresses to fetch balances for
filter.contractWhitelist	string[]	(Optional) Array of contract addresses to include
filter.contractBlacklist	string[]	(Optional) Array of contract addresses to exclude
filter.omitNativeBalances	boolean	(Optional) If true, excludes native token balances
filter.contractStatus	ContractVerificationStatus	(Optional) Filter for contract verification status

options: BalanceHookOptions

interface BalanceHookOptions {
  disabled?: boolean
  retry?: boolean
  hideCollectibles?: boolean
}

Parameter	Type	Description
disabled	boolean	(Optional) Disable the query from automatically running
retry	boolean	(Optional) Whether to retry failed queries
hideCollectibles	boolean	(Optional) If true, filters out ERC721 and ERC1155 tokens